August 22 PUB -- *.SAI and PUBSTD.DFS[OK,TES] at SU-AI.



                *** EVENLEFTBORDER, ODDLEFTBORDER ***


These variables in XGP mode  specify the left border widths  in mills
of even and  odd numbered pages.  They  both start out at  1300 mills
(1.3 inches) and  the minimum value possible  on our XGP is  500 (1/2
inch).  Any change you make will take effect on the next page that is
closed.
                 ---- If you want this feature: ----
  --- Make the appropriate settings for your XGP in PUBDFS.SAI ---.
     ---- and adapt all code dealing with LFTMAR in pub2.sai ---

The  title  page  has special  considerations.   When  you  begin the
manuscript,  PAGE=PAGE!=NULL,  signifying an  unnumbered  title page.
Its border will be ODDLEFTBORDER to be consistent with the  way books
are  made.   However, if  you  set PAGE←0  (but  leave  PAGE!=NULL to
inhibit numbering) then the title page will get an even left border.

If  you find  that  your page  images are  too  far to  the  right in
documents that used to look OK, this may be because the  default left
borders used to be 1 inch.  The  easiest fix is to put at the  top of
the manuscript or in your own DFS file the statement  ODDLEFTBORDER ←
EVENLEFTBORDER ← 1000.


                          *** !XGPINTRA ***


You  can change  the intra-line  spacing on  the XGP  for  the entire
document by setting !xgpintra to  some value other than its  normal 3
raster units (.015 inch).
                 ---- if you want this feature: ---
               --- pass 2 knows the value as INTRA ---
 --- See how we tell our XGP and do something similar if you can ---


    *** PROCEDURE name(args,...) $( ... RETURN(value) ... )$ ***


A procedure is a variety  of macro.  The advantage of a  procedure is
that it may RETURN at any time, with or without a value.  The default
RETURN is RETURN(NULL).

Example:



        .PROCEDURE DOUBLE(N) $( N ← N+N; RETURN("OK") )$
        .X ← 5 ;
        .TTY ← DOUBLE(X) ;
This will set X to 10  and print OK on the terminal.  Good  news: the
restriction  on recursive  macros which  sometimes requires  a double
semicolon is not applicable to procedures.  Bad news:  procedures are
as slow as macros, i.e., very slow.


                  *** REPEAT $( ... DONE ... )$ ***


The command REPEAT followed by a template will execute  that template
repeatedly until the statement DONE is executed.  Example:
        .PROCEDURE FACTORIAL(↑F N)
        .$( << ↑F means N is a value parameter >>
        .ANS ← I ← 1 ;
        .REPEAT$( ANS←ANS*I ; I←I+1 ; IF I>N THEN DONE )$
        .RETURN(ANS)
        .)$
        .TTY←FACTORIAL(4)
This will print 24 on the terminal.


        *** WHILE(pretest,action), UNTIL(posttest,action) ***


These macros will execute the <action> repeatedly while the <pretest>
before each  repetition is  true or until  the <posttest>  after some
repetition is true.  Their arguments usually are enclosed in vertical
bars.


                          *** PUB!DEBUG ***


The PUB!DEBUG command provides an interactive debugging facility.  It
allows   for  both examination  of  the state  of  a  compilation and
keyboard entry of commands.

PUB!DEBUG goes into a "read-eval-print" loop.

It  prompts with  #  and waits  for you  to  type a  segment  of text
terminated by <cr> or <esc>.  While typing the segment, ↑A  deletes a
character, ↑V  accepts the next  character literally, ↑S  retypes the
segment, and <del> starts  over.  LF starts a continuation  line, and
the current continuation line can be deleted by ↑Q.



       --- continuation lines are only implemented at PARC ---
     --- they are handled by PUB's own INCHWL in PARSER.SAI ---
    --- The edit control characters are those in your system ---

PUB!DEBUG expects the first line of  the segment to be in one  of the
following forms:
        <expression>
        <expression> ; <commands>
        ; <commands>
The value of the <expression> is printed, and then the <commands> are
executed.

If  there  are  continuation  lines,  they  are  expected  to  be  in
manuscript format.   Command lines start  with the  command character
(usually period); text lines do not.

It is legal to include temporarily unmatched BEGINs, STARTs, and ENDs
in the segment, but unmatched template brackets will cause havoc of a
very unpleasant sort (for now anyway).

The read-eval-print loop is terminated as soon as an empty segment is
typed (i.e., just <cr>).


                          *** THISLINE ***


A useful variable  to examine while  debugging is THISLINE,  which is
the current output line  formed so far by  PUB.  It is NULLed  out by
every  line break.   In  it, word  breaks  are represented  by  $ and
forward references by ↑K<number>.


                         *** BURP INPUT ***


To  discover your  context while  debugging, execute  the  BURP INPUT
command.  It types out some of the yet unparsed input at  the current
level and at  several previous levels  of macros and  requires.  BURP
INPUT VERBOSE may type out more characters at each level,  and always
proceeds to the outermost level.


                         *** BURP AREAS ***


If  you are  hopelessly fouled  up with  area declarations,  try BURP



AREAS, which  types out  10-30 lines of  information about  all areas
known by PUB, even those that are inaccessible in outer blocks.  BURP
AREAS VERBOSE includes  a picture of each  area that has text  in it,
with numbers  that reference  the numbers  found in  the intermediate
".TXTn" files.


             *** DEBUG("herald"), DEBUGFLAG, BUGOFF ***


A convenient way  to activate PUB!DEBUG is  by planting calls  on the
macro DEBUG("herald") throughout the manuscript.  The herald (if any)
is printed, and  then PUB!DEBUG is called.   However, the macro  is a
no-op if the variable DEBUGFLAG is FALSE.  An easy way to turn it off
is by calling the macro BUGOFF.


                   *** ERROR MESSAGE RESPONSES ***


Most  SAIL and  PUB error  messages are  now handled  by a  new error
handler providing somewhat more useful information than before.

In addition to  the usual responses (CR  to continue, LF  to continue
automatically, X to exit, S to  restart), you can now type P  to call
PUB!DEBUG.
        --- At SU-AI and CMU, E<cr> does the right thing. ---
               --- T<cr> might work at SU-AI too. ---

A LF to continue automatically  sets the variable ERRLF to  TRUE.  It
can be cancelled by the command ERRLF←FALSE either in  the manuscript
or in a debug loop.


                      *** USERERR "message" ***


Thanks to  Rich Johnsson,  this command lets  you activate  the error
machinery yourself.


                      *** XLENGTH("string") ***


If in XGP mode, XLENGTH returns the raster width of the string in the
current font.  For other devices, it returns 0.



                            *** SCAN ***


Adopted from  SAIL by  request of  Lee Erman,  this function  scans a
string in search of break characters and can divide the string into a
pre-break and a post-break substring.  The various forms of  call, in
order of increasing complexity, are:

ANS←SCAN(STR,STOPPERS) scans the string  STR in search of any  of the
break characters listed in STOPPERS.  If one is found, then  ANS← the
substring before the break character,  and if STR is a  variable then
STR← the substring that  remains, retaining the break  character.  If
no break character is found,  then ANS←STR, and if STR is  a variable
then STR←NULL.

ANS←SCAN(STR,STOPPERS,OMITS) is similar but characters in  the string
OMITS are dropped from ANS.

ANS←SCAN(STR,STOPPERS,OMITS,OPTIONS) where  OPTIONS is a  string with
an (R,  A, or  S) and  an (I  or X)  varies the  behavior of  SCAN as
follows:
        R       Retain break character in STR (Default)
        A       Append break character to ANS instead
        S       Skip break character -- neither STR nor ANS

        I       "Inclusive": Break characters are
                        those in STOPPERS (Default)
        X       "eXclusive": Break characters are all ascii
                        characters EXCEPT those in STOPPERS

ANS←SCAN(STR,STOPPERS,OMITS,OPTIONS,BRCVAR)   where   BRCVAR   is   a
variable name, sets BRCVAR  to a one-character string  containing the
break  character  which  actually  stopped  the  scan.   If  no break
character was found, then BRCVAR←NULL.

The  effect  of  SAIL  break tables  can  be  had  (functionally, not
speedily) by the use of a macro to supply the middle arguments of the
function call.


                       *** OCTAL("string") ***


OCTAL  returns the  octal codes  of the  characters in  its argument,
e.g., OCTAL("ABC")="'101'102'103".  If the value of OCTAL is  used in
arithmetic, only the code of the first character is involved.



                   *** BEWARE("'octal'values") ***


For   generality,   the   inverse  of   OCTAL   is   provided,  i.e.,
BEWARE("'101'102'103")="ABC".  The function is so named to remind you
that the insertion of a  cr, lf, tab, vtab, altmode, rubout,  or null
in a text line will hopelessly confuse PUB and forfeit your  right to
aid or sympathy.


                   *** DECLARATION(identifier) ***


Borrowed from SAIL  by request of Lee  Erman, this function  takes an
identifier as  an argument  and returns its  PUB internal  type code.
The most useful value of DECLARATION(X) is 0 (FALSE)  which signifies
that X is undeclared.


                 *** TABS PAST THE LAST TAB STOP ***


These used  to produce an  error message, but  by request of  Ed Taft
they now quietly emit a single space.


                   *** UNDERLINING IN XGP MODE ***


This will look  slightly different -- usually  better -- thanks  to a
request by Dan Bobrow that PUB emit the  sequence underbar-backspace-
character instead of character-backspace-underbar.


                    *** HEMLINES IN XGP MODE ***


These may also look a bit different, because Rich Johnsson  has fixed
a bug in forward reference code.